home *** CD-ROM | disk | FTP | other *** search
/ Aminet 1 (Walnut Creek) / Aminet - June 1993 [Walnut Creek].iso / usenet / sources / volume91 / devices / sanainov / part03 / sana2device.doc
Text File  |  1991-11-16  |  28KB  |  998 lines
  1. TABLE OF CONTENTS
  2.  
  3. sana2.device/AbortIO
  4. sana2.device/CloseDevice
  5. sana2.device/CMD_CLEAR
  6. sana2.device/CMD_FLUSH
  7. sana2.device/CMD_INVALID
  8. sana2.device/CMD_READ
  9. sana2.device/CMD_RESET
  10. sana2.device/CMD_START
  11. sana2.device/CMD_STOP
  12. sana2.device/CMD_UPDATE
  13. sana2.device/CMD_WRITE
  14. sana2.device/OpenDevice
  15. sana2.device/S2_ADDMULTICASTADDRESS
  16. sana2.device/S2_BROADCAST
  17. sana2.device/S2_CONFIGINTERFACE
  18. sana2.device/S2_DELMULTICASTADDRESS
  19. sana2.device/S2_DEVICEQUERY
  20. sana2.device/S2_GETGLOBALSTATS
  21. sana2.device/S2_GETSPECIALSTATS
  22. sana2.device/S2_GETSTATIONADDRESS
  23. sana2.device/S2_GETTYPESTATS
  24. sana2.device/S2_MULTICAST
  25. sana2.device/S2_OFFLINE
  26. sana2.device/S2_ONEVENT
  27. sana2.device/S2_ONLINE
  28. sana2.device/S2_READORPHAN
  29. sana2.device/S2_TRACKTYPE
  30. sana2.device/S2_UNTRACKTYPE
  31. sana2.device/AbortIO                                     sana2.device/AbortIO
  32.  
  33.    NAME
  34.     AbortIO -- Remove an existing device request.
  35.  
  36.    SYNOPSIS
  37.     error = AbortIO(Sana2Req)
  38.     D0              A1
  39.  
  40.     LONG AbortIO(struct IOSana2Req *);
  41.  
  42.    FUNCTION
  43.     This is an exec.library call.
  44.  
  45.     This function aborts an ioRequest. If the request is active, it may or
  46.     may not be aborted. If the request is queued it is removed. The
  47.     request will be returned in the same way as if it had normally
  48.     completed.  You must WaitIO() after AbortIO() for the request to
  49.     return.
  50.  
  51.    INPUTS
  52.     Sana2Req    - Sana2Req to be aborted.
  53.  
  54.    RESULTS
  55.     error        - Zero if the request was aborted, non-zero otherwise.
  56.               io_Error in Sana2Req will be set to IOERR_ABORTED
  57.               if it was aborted.
  58.  
  59.    NOTES
  60.  
  61.    SEE ALSO
  62.     exec.library/AbortIO(), exec.library/WaitIO()
  63.  
  64.    BUGS
  65.  
  66. sana2.device/CloseDevice                             sana2.device/CloseDevice
  67.  
  68.    NAME
  69.     CloseDevice -- Close the device.
  70.  
  71.    SYNOPSIS
  72.     CloseDevice(Sana2Req)
  73.             A1
  74.  
  75.     void CloseDevice(struct IOSana2Req *);
  76.  
  77.    FUNCTION
  78.     This function is called by exec.library CloseDevice().
  79.  
  80.     This function performs whatever cleanup is required at device closes.
  81.  
  82.     Note that all IORequests MUST be complete before closing. If any are
  83.     pending, your program must AbortIO() then WaitIO() each outstanding
  84.     IORequest to complete them.
  85.  
  86.    INPUTS
  87.     Sana2Req    - Pointer to IOSana2Req initialized by OpenDevice().
  88.  
  89.    NOTES
  90.  
  91.    SEE ALSO
  92.     exec.library/CloseDevice(), exec.library/OpenDevice()
  93.  
  94.    BUGS
  95.  
  96. sana2.device/CMD_CLEAR                                 sana2.device/CMD_CLEAR
  97.  
  98.    NAME
  99.     Clear -- Clear internal network interface read buffers.
  100.  
  101.    FUNCTION
  102.     There are no device internal buffers, so CMD_CLEAR does not apply to
  103.     this class of device.
  104.  
  105.    IO REQUEST
  106.     ios2_Command    - CMD_CLEAR.
  107.  
  108.    RESULTS
  109.     ios2_Error    - IOERR_NOCMD.
  110.  
  111.    NOTES
  112.  
  113.    SEE ALSO
  114.  
  115.    BUGS
  116.  
  117. sana2.device/CMD_FLUSH                                 sana2.device/CMD_FLUSH
  118.  
  119.    NAME
  120.     Flush -- Clear all queued I/O requests for the SANA-II device.
  121.  
  122.    FUNCTION
  123.     This command aborts all I/O requests in both the read and write
  124.     request queues of the device.  All pending I/O requests are
  125.     returned with an error message (IOERR_ABORTED).  CMD_FLUSH does not
  126.     effect active requests.
  127.  
  128.    IO REQUEST
  129.     ios2_Command    - CMD_FLUSH.
  130.  
  131.    RESULTS
  132.     ios2_Error    - Zero if successful; non-zero otherwise.
  133.  
  134.    NOTES
  135.  
  136.    SEE ALSO
  137.  
  138.    BUGS
  139.  
  140. sana2.device/CMD_INVALID                             sana2.device/CMD_INVALID
  141.  
  142.    NAME
  143.     Invalid -- Return with error IOERR_NOCMD.
  144.  
  145.    FUNCTION
  146.     This command causes device driver to reply with an error IOERR_NOCMD
  147.     as defined in <exec/errors.h> indicating the command is not supported.
  148.  
  149.    IO REQUEST
  150.     ios2_Command    - CMD_INVALID.
  151.  
  152.    RESULTS
  153.     ios2_Error    - IOERR_NOCMD.
  154.  
  155.    NOTES
  156.  
  157.    SEE ALSO
  158.  
  159.    BUGS
  160.     Not known to be useful.
  161.  
  162. sana2.device/CMD_READ                                   sana2.device/CMD_READ
  163.  
  164.    NAME
  165.     Read -- Get a packet from the network.
  166.  
  167.    FUNCTION
  168.     Get the next packet available of the requested packet type. The data
  169.     copied (via a call to the requestor-provided CopyToBuffer function)
  170.     into ios2_Data is normally the Data Link Layer packet data only. If
  171.     bit SANA2IOB_RAW is set in ios2_Flags, then the entire physical frame
  172.     will be returned.
  173.  
  174.     Unlike most Exec devices, SANA-II device drivers do not have internal
  175.     buffers.  If you wish to read data from a SANA-II device you should
  176.     have multiple CMD_READ requests pending at any given time.  The
  177.     functions provided by you the requestor will be used for any incoming
  178.     packets of the type you've requested.  If no read requests are
  179.     outstanding for a type which comes in and no read_orphan requests are
  180.     outstanding, the packet will be lost.
  181.  
  182.    IO REQUEST
  183.     ios2_Command    - CMD_READ
  184.     ios2_Flags    - Supported flags are:
  185.                         SANA2IOB_RAW
  186.                         SANA2IOB_QUICK
  187.     ios2_PacketType    - Pointer to packet type desired.
  188.     ios2_Body    - Abstract data structure to hold packet data.
  189.  
  190.    RESULTS
  191.     ios2_Error    - Zero if successful; non-zero otherwise.
  192.     ios2_WireError    - More specific error number.
  193.     ios2_Flags    - The following flags may be returned:
  194.                         SANA2IOB_RAW
  195.                         SANA2IOB_BCAST
  196.                         SANA2IOB_MCAST
  197.     ios2_SrcAddr    - Source interface address of packet.
  198.     ios2_DstAddr    - Destination interface address of packet.
  199.     ios2_DataLength    - Length of packet data.
  200.     ios2_Data    - Abstract data structure which packet data is
  201.               contained in.
  202.  
  203.    NOTES
  204.     The driver may not directly examine or modify anything pointed to by
  205.     ios2_Data.  It *must* use the requester-provided functions to access
  206.     this data.
  207.  
  208.    SEE ALSO
  209.     S2_READORPHAN, CMD_WRITE, any_protocol/CopyToBuffer
  210.  
  211.    BUGS
  212.  
  213. sana2.device/CMD_RESET                                 sana2.device/CMD_RESET
  214.  
  215.    NAME
  216.     Reset -- Reset the network interface to initialized state.
  217.  
  218.    FUNCTION
  219.     Currently, SANA-II devices can only be configured once (with
  220.     CMD_CONFIGINTERFACE) and cannot be re-configured, hence,
  221.     CMD_RESET does not apply to this class of device.
  222.  
  223.    IO REQUEST
  224.     ios2_Command    - CMD_RESET.
  225.  
  226.    RESULTS
  227.     ios2_Error    - IOERR_NOCMD.
  228.  
  229.    NOTES
  230.  
  231.    SEE ALSO
  232.  
  233.    BUGS
  234.  
  235. sana2.device/CMD_START                                 sana2.device/CMD_START
  236.  
  237.    NAME
  238.     Start -- Restart device operation.
  239.  
  240.    FUNCTION
  241.     There is no way for the driver to keep queuing requests without
  242.     servicing them, so CMD_STOP does not apply to this class of device.
  243.     S2_OFFLINE and S2_ONLINE do perform a similar function to CMD_STOP
  244.     and CMD_START
  245.  
  246.    IO REQUEST
  247.     ios2_Command    - CMD_START.
  248.  
  249.    RESULTS
  250.     ios2_Error    - IOERR_NOCMD.
  251.  
  252.    NOTES
  253.  
  254.    SEE ALSO
  255.     S2_ONLINE, S2_OFFLINE
  256.  
  257.    BUGS
  258.  
  259. sana2.device/CMD_STOP                                   sana2.device/CMD_STOP
  260.  
  261.    NAME
  262.     Stop -- Pause device operation.
  263.  
  264.    FUNCTION
  265.     There is no way for the driver to keep queuing requests without
  266.     servicing them, so CMD_STOP does not apply to this class of device.
  267.     S2_OFFLINE and S2_ONLINE do perform a similar function to CMD_STOP
  268.     and CMD_START
  269.  
  270.    IO REQUEST
  271.     ios2_Command    - CMD_STOP.
  272.  
  273.    RESULTS
  274.     ios2_Error    - IOERR_NOCMD.
  275.  
  276.    NOTES
  277.  
  278.    SEE ALSO
  279.     S2_ONLINE, S2_OFFLINE
  280.  
  281.    BUGS
  282.  
  283. sana2.device/CMD_UPDATE                               sana2.device/CMD_UPDATE
  284.  
  285.    NAME
  286.     Update -- Force packets out to device.
  287.  
  288.    FUNCTION
  289.     Since there are no device internal buffers, CMD_UPDATE does not
  290.     apply to this class of device.
  291.  
  292.    IO REQUEST
  293.     ios2_Command    - CMD_UPDATE.
  294.  
  295.    RESULTS
  296.     ios2_Error    - IOERR_NOCMD.
  297.  
  298.    NOTES
  299.  
  300.    SEE ALSO
  301.  
  302.    BUGS
  303.  
  304. sana2.device/CMD_WRITE                                 sana2.device/CMD_WRITE
  305.  
  306.    NAME
  307.     Write -- Send packet to the network.
  308.  
  309.    FUNCTION
  310.     This command causes the packet to be sent to the specified network
  311.     interface. Normally, appropriate packet header and trailer information
  312.     will be added to the packet data when it is sent.  If bit SANA2IOB_RAW
  313.     is set in io_Flags, then the ios2_Data is assumed to contain an entire
  314.     physical frame and will be sent (copied to the wire via
  315.     CopyFromBuffer() unmodified.
  316.  
  317.     Note that the device should not check to see if the destination
  318.     address is on the local hardware.  Network protocols should realize
  319.     that the packet has a local destination long before it gets to a
  320.     SANA-II driver.
  321.  
  322.    IO REQUEST
  323.     ios2_Command    - CMD_WRITE.
  324.     ios2_Flags    - Supported flags are:
  325.                         SANA2IOB_RAW
  326.                         SANA2IOB_QUICK
  327.     ios2_PacketType    - Pointer to type of packet to send.
  328.     ios2_DstAddr    - Destination interface address for this packet.
  329.     ios2_DataLength    - Length of the Data to be sent.
  330.     ios2_Data    - Abstract data structure which packet data is
  331.               contained in.
  332.  
  333.    RESULTS
  334.     ios2_Error    - Zero if successful; non-zero otherwise.
  335.     ios2_WireError    - More specific error number.
  336.  
  337.    NOTES
  338.     The driver may not directly examine or modify anything pointed to by
  339.     ios2_Data.  It *must* use the requester-provided functions to access
  340.     this data.
  341.  
  342.    SEE ALSO
  343.     CMD_READ, S2_BROADCAST, S2_MULTICAST, any_protocol/CopyFromBuffer
  344.  
  345.    BUGS
  346.  
  347. sana2.device/OpenDevice                               sana2.device/OpenDevice
  348.  
  349.    NAME
  350.     Open -- Request an opening of the network device.
  351.  
  352.    SYNOPSIS
  353.     error = OpenDevice(unit, IOSana2Req, flags)
  354.     D0           D0    A1          D1
  355.  
  356.     BYTE OpenDevice(ULONG, struct IOSana2Req *, ULONG);
  357.  
  358.    FUNCTION
  359.     This function is called by exec.library OpenDevice().
  360.  
  361.     This function performs whatever initialization is required per
  362.     device open and initializes the Sana2Req for use by the
  363.     device.
  364.  
  365.    INPUTS
  366.     unit        - Device unit to open.
  367.     Sana2Req    - Pointer to IOSana2Req structure to be initialized by
  368.               the sana2.device.
  369.     flags        - Supported flags are:
  370.                 SANA2OPB_MINE
  371.                 SANA2OPB_PROM
  372.     ios2_BufferManagement    - A pointer to a tag list containing
  373.                   pointers to buffer management functions.
  374.  
  375.    RESULTS
  376.     error        - same as io_Error
  377.     io_Error    - Zero if successful; non-zero otherwise.
  378.     io_Device    - A pointer to whatever device will handle the calls
  379.               for this unit.  This pointer may be different
  380.               depending on what unit is requested.
  381.     ios2_BufferManagement    - A pointer to device internal information
  382.                   used to call buffer management functions.
  383.  
  384.    NOTES
  385.  
  386.    SEE ALSO
  387.     exec.library/OpenDevice(), exec.library/CloseDevice()
  388.  
  389.    BUGS
  390.  
  391. sana2.device/S2_ADDMULTICASTADDRESS       sana2.device/S2_ADDMULTICASTADDRESS
  392.  
  393.    NAME
  394.     AddMulticastAddress -- Enable an interface multicast address.
  395.  
  396.    FUNCTION
  397.     This command causes the device driver to enable multicast packet
  398.     reception for the requested address.
  399.  
  400.    IO REQUEST
  401.     ios2_Command    - S2_ADDMULTICASTADDRESS.
  402.     ios2_SrcAddr    - Multicast address to enable.
  403.  
  404.    RESULTS
  405.     ios2_Error    - Zero if successful; non-zero otherwise.
  406.     ios2_WireError    - More specific error number.
  407.  
  408.    NOTES
  409.     Multicast addresses are added globally -- anyone using the device
  410.     may receive packets as a result of any multicast address which has
  411.     been added for the device.
  412.  
  413.     Since multicast addresses are not "bound" to a particular packet type,
  414.     each enabled multicast address has an "enabled" count associated with
  415.     it so that if two protocols add the same multicast address and later
  416.     one removes it, it is still enabled until the second removes it.
  417.  
  418.    SEE ALSO
  419.     S2_MULTICAST, S2_DELMULTICASTADDRESS
  420.  
  421.    BUGS
  422.  
  423. sana2.device/S2_BROADCAST                           sana2.device/S2_BROADCAST
  424.  
  425.    NAME
  426.     Broadcast -- Broadcast a packet on network.
  427.  
  428.    FUNCTION
  429.     This command works the same as CMD_WRITE except that it also performs
  430.     whatever special processing of the packet is required to do a
  431.     broadcast send. The actual broadcast mechanism is neccessarily
  432.     network/interface/device specific.
  433.  
  434.    IO REQUEST
  435.     ios2_Command    - S2_BROADCAST.
  436.     ios2_Flags    - Supported flags are:
  437.                 SANA2IOB_RAW
  438.                 SANA2IOB_QUICK
  439.     ios2_PacketType    - Pointer to type of packet to send.
  440.     ios2_DataLength    - Length of the Data to be sent.
  441.     ios2_Data    - Abstract data structure which packet data is
  442.               contained in.
  443.  
  444.    RESULTS
  445.     ios2_DstAddr    - The contents of this field are to be
  446.               considered trash upon return of the IOReq.
  447.     ios2_Error    - Zero if successful; non-zero otherwise.
  448.                       This command can fail for many reasons and
  449.                       is not supported by all networks and/or
  450.                       network interfaces.
  451.     ios2_WireError    - More specific error number.
  452.  
  453.    NOTES
  454.     The DstAddr field may be trashed by the driver because this function
  455.     may be implemented by filling DstAddr with a broadcast address and
  456.     internally calling CMD_WRITE.
  457.  
  458.    SEE ALSO
  459.     CMD_WRITE, S2_MULTICAST
  460.  
  461.    BUGS
  462.  
  463. sana2.device/S2_CONFIGINTERFACE               sana2.device/S2_CONFIGINTERFACE
  464.  
  465.    NAME
  466.     ConfigInterface -- Configure the network interface.
  467.  
  468.    FUNCTION
  469.     This command causes the device driver to initialize the interface
  470.     hardware and to set the network interface address to the address in
  471.     ios2_SrcAddr. This command can only be executed once and, if
  472.     successful, will leave the driver and network interface fully
  473.     operational and the network interface in ios2_SrcAddr.
  474.  
  475.     To set the interface address to the factory address, the network
  476.     management software must use GetStationAddress first and then call
  477.     ConfigInterface with the result. If there is no factory address then
  478.     the network software must pick an address to use.
  479.  
  480.     Until this command is executed the device will not listen for any
  481.     packets on the hardware.
  482.  
  483.    IO REQUEST
  484.     ios2_Command    - S2_CONFIGINTERFACE.
  485.     ios2_Flags      - Supported flags are:
  486.                 SANA2IOB_QUICK
  487.     ios2_SrcAddr    - Address for this interface.
  488.  
  489.    RESULTS
  490.     ios2_Error    - Zero if successful; non-zero otherwise.
  491.     ios2_WireError    - More specific error number.
  492.     ios2_SrcAddr    - Address of this interface as configured.
  493.  
  494.    NOTES
  495.     Some networks have the interfaces choose a currently unused interface
  496.     address each time the interface is initialized. The caller must check
  497.     ios2_SrcAddr for the actual interface address after configuring the
  498.     interface.
  499.  
  500.    SEE ALSO
  501.     S2_GETSTATIONADDRESS
  502.  
  503.    BUGS
  504.  
  505. sana2.device/S2_DELMULTICASTADDRESS       sana2.device/S2_DELMULTICASTADDRESS
  506.  
  507.    NAME
  508.     DelMultiCastAddress -- Disable an interface multicast address.
  509.  
  510.    FUNCTION
  511.     This command causes device driver to disable multicast packet
  512.     reception for the requested address.
  513.  
  514.     It is an error to disable a multicast address that is not enabled.
  515.  
  516.    IO REQUEST
  517.     ios2_Command    - S2_DELMULTICASTADDRESS
  518.     ios2_SrcAddr    - Multicast address to disable.
  519.  
  520.    RESULTS
  521.     ios2_Error    - Zero if successful; non-zero otherwise.
  522.     ios2_WireError    - More specific error number.
  523.  
  524.    NOTES
  525.     Multicast addresses are added globally -- anyone using the device
  526.     may receive packets as a result of any multicast address which has
  527.     been added for the device.
  528.  
  529.     Since multicast addresses are not "bound" to a particular packet type,
  530.     each enabled multicast address has an "enabled" count associated with
  531.     it so that if two protocols add the same multicast address and later
  532.     one removes it, it is still enabled until the second removes it.
  533.  
  534.    SEE ALSO
  535.     S2_ADDMULTICASTADDRESS
  536.  
  537.    BUGS
  538.  
  539. sana2.device/S2_DEVICEQUERY                       sana2.device/S2_DEVICEQUERY
  540.  
  541.    NAME
  542.     DeviceQuery -- Return parameters for this network interface.
  543.  
  544.    FUNCTION
  545.     This command causes the device driver to report information about the
  546.     device. Up to SizeAvailable bytes of the information is copied
  547.     into a buffer pointed to by ios2_StatData. The format of the data is
  548.     as follows:
  549.  
  550.         struct Sana2DeviceQuery
  551.         {
  552.         /*
  553.         ** Standard information
  554.         */
  555.             ULONG SizeAvailble; /* bytes available */
  556.             ULONG SizeSupplied; /* bytes supplied */
  557.             LONG  DevQueryFormat;   /* this is type 0 */
  558.             LONG  DeviceLevel;      /* this document is level 0 */
  559.  
  560.         /*
  561.         ** Common information
  562.         */
  563.             UWORD AddrFieldSize;    /* address size in bits */
  564.             ULONG MTU;              /* maximum packet data size */
  565.             LONG  bps;              /* line rate (bits/sec) */
  566.             LONG  HardwareType;     /* what the wire is */
  567.  
  568.         /*
  569.         ** Format specific information
  570.         */
  571.         };
  572.  
  573.     The SizeAvailable specifies the number of bytes that the caller
  574.     is prepared to accomodate, including the standard information fields.
  575.  
  576.     SizeSupplied is the number of bytes actually supplied,
  577.     including the standard information fields, which will not exceed
  578.     SizeAvailable.
  579.  
  580.     <devices/sana2.h> includes constants for these values.  If your
  581.     hardware does not have a number assigned to it, you must contact
  582.     CATS to get a hardware number.
  583.  
  584.    IO REQUEST
  585.     ios2_Command    - S2_DEVICEQUERY.
  586.     ios2_StatData    - Pointer to Sana2DeviceQuery structure to fill in.
  587.  
  588.    RESULTS
  589.     ios2_Error    - Zero if successful; non-zero otherwise.
  590.     ios2_WireError    - More specific error number.
  591.  
  592.    NOTES
  593.  
  594.    SEE ALSO
  595.  
  596.    BUGS
  597.  
  598. sana2.device/S2_GETGLOBALSTATS                 sana2.device/S2_GETGLOBALSTATS
  599.  
  600.    NAME
  601.     GetGlobalStats -- Get interface accumulated statistics.
  602.  
  603.    FUNCTION
  604.     This command causes the device driver to retrieve various global
  605.     runtime statistics for this network interface. The format of the
  606.     data returned is as follows:
  607.  
  608.         struct Sana2DeviceStats
  609.         {
  610.             LONG packets_received;
  611.             LONG packets_sent;
  612.             LONG framming_errors;
  613.             LONG bad_data;
  614.             LONG bytes_received;
  615.             LONG bytes_sent;
  616.             LONG hard_misses;
  617.             LONG soft_misses;
  618.             LONG unknown_types_received;
  619.             LONG fifo_overruns;
  620.             LONG fifo_underruns;
  621.             LONG reconfigurations;
  622.             timeval last_start;
  623.         };
  624.  
  625.    IO REQUEST
  626.     ios2_Command    - S2_GETGLOBALSTATS.
  627.     ios2_StatData    - Pointer to Sana2DeviceStats structure to fill.
  628.  
  629.    RESULTS
  630.     ios2_Error    - Zero if successful; non-zero otherwise.
  631.     ios2_WireError    - More specific error number.
  632.  
  633.    NOTES
  634.  
  635.    SEE ALSO
  636.     S2_GETSPECIALSTATS
  637.  
  638.    BUGS
  639.  
  640. sana2.device/S2_GETSPECIALSTATS               sana2.device/S2_GETSPECIALSTATS
  641.  
  642.    NAME
  643.     GetSpecialStats -- Get network type specific statistics.
  644.  
  645.    FUNCTION
  646.     This function returns statistics which are specific to the type of
  647.     network medium this driver controls. For example, this command could
  648.     return statistics common to all Ethernets which are not common to all
  649.     network mediums in general.
  650.  
  651.     The supplied Sana2SpecialStatData structure is given below:
  652.  
  653.         struct Sana2SpecialStatData
  654.         {
  655.             ULONG RecordCountMax;
  656.             ULONG RecordCountSupplied;
  657.             struct Sana2StatRecord[RecordCountMax];
  658.         };
  659.  
  660.     The format of the data returned is:
  661.  
  662.         struct Sana2StatRecord
  663.         {
  664.             ULONG Type;     /* commodore registered */
  665.             LONG Count;     /* the stat itself */
  666.             char *String;   /* null terminated */
  667.         };
  668.  
  669.     The RecordCountMax field specifies the number of records that the
  670.     caller is prepared to accomodate.
  671.  
  672.     RecordCountSupplied is the number of record actually supplied which
  673.     will not exceed RecordCountMax.
  674.  
  675.    IO REQUEST
  676.     ios2_Command    - S2_GETSPECIALSTATS.
  677.     ios2_StatData    - Pointer to a Sana2SpecialStatData structure to fill.
  678.               RecordCountMax must be initialized.
  679.  
  680.    RESULTS
  681.     ios2_Error    - Zero if successful; non-zero otherwise.
  682.     ios2_WireError    - More specific error number.
  683.  
  684.    NOTES
  685.     Commodore will maintain registered statistic Types.
  686.  
  687.    SEE ALSO
  688.     S2_GETGLOBALSTATS, <devices/sana2specialstats.h>
  689.  
  690.    BUGS
  691.  
  692. sana2.device/S2_GETSTATIONADDRESS           sana2.device/S2_GETSTATIONADDRESS
  693.  
  694.    NAME
  695.     GetStationAddress -- Get default and interface address.
  696.  
  697.    FUNCTION
  698.     This command causes the device driver to copy the current interface
  699.     address into ios2_SrcAddr, and to copy the factory default station
  700.     address (if any) into ios2_DstAddr.
  701.  
  702.    IO REQUEST
  703.     ios2_Command    - S2_GETSTATIONADDRESS.
  704.  
  705.    RESULTS
  706.     ios2_Error    - Zero if successful; non-zero otherwise.
  707.     ios2_WireError    - More specific error number.
  708.     ios2_SrcAddr    - Current interface address.
  709.     ios2_DstAddr    - Default interface address (if any).
  710.  
  711.    NOTES
  712.  
  713.    SEE ALSO
  714.     S2_CONFIGINTERFACE
  715.  
  716.    BUGS
  717.  
  718. sana2.device/S2_GETTYPESTATS                     sana2.device/S2_GETTYPESTATS
  719.  
  720.    NAME
  721.     GetTypeStats -- Get accumulated type specific statistics.
  722.  
  723.    FUNCTION
  724.     This command causes the device driver to retrieve various packet type
  725.     specific runtime statistics for this network interface. The format of
  726.     the data returned is as follows:
  727.  
  728.         struct Sana2TypeStatData
  729.         {
  730.             LONG PacketsSent;
  731.             LONG PacketsReceived;
  732.             LONG BytesSent;
  733.             LONG BytesReceived;
  734.             LONG PacketsDropped;
  735.         };
  736.  
  737.    IO REQUEST
  738.     ios2_Command    - S2_GETTYPESTATS.
  739.     ios2_PacketType    - Pointer to the packet type of interest.
  740.     ios2_StatData    - Pointer to TypeStatData structure to fill in.
  741.  
  742.    RESULTS
  743.     ios2_Error    - Zero if successful; non-zero otherwise.
  744.     ios2_WireError    - More specific error number.
  745.  
  746.    NOTES
  747.     Statistics for a particular packet type are only available while that
  748.     packet type is being ``tracked''.
  749.  
  750.    SEE ALSO
  751.     S2_TRACKTYPE, S2_UNTRACKTYPE
  752.  
  753.    BUGS
  754.  
  755. sana2.device/S2_MULTICAST                           sana2.device/S2_MULTICAST
  756.  
  757.    NAME
  758.     Multicast -- Multicast a packet on network.
  759.  
  760.    FUNCTION
  761.     This command works the same as CMD_WRITE except that it also performs
  762.     whatever special processing of the packet is required to do a
  763.     multicast send. The actual multicast mechanism is neccessarily
  764.     network/interface/device specific.
  765.  
  766.    IO REQUEST
  767.     ios2_Command    - S2_MULTICAST.
  768.     ios2_Flags    - Supported flags are:
  769.                 SANA2IOB_RAW
  770.                 SANA2IOB_QUICK
  771.     ios2_PacketType    - Pointer to type of packet to send.
  772.     ios2_DstAddr    - Destination interface address for this packet.
  773.     ios2_DataLength    - Length of the Data to be sent.
  774.     ios2_Data    - Abstract data structure which packet data is
  775.               contained in.
  776.  
  777.    RESULTS
  778.     ios2_Error    - Zero if successful; non-zero otherwise.
  779.                       This command can fail for many reasons and
  780.                       is not supported by all networks and/or
  781.                       network interfaces.
  782.     ios2_WireError    - More specific error number.
  783.  
  784.    NOTES
  785.     The address supplied in ios2_DstAddr will be sanity checked (if
  786.     possible) by the driver. If the supplied address fails this sanity
  787.     check, the multicast request will fail immediately with ios2_Error
  788.     set to S2WERR_BAD_MULTICAST.
  789.  
  790.     Another Amiga will not receive a multicast packet unless it has had
  791.     the particular multicast address being used S2_ADDMULTICASTADRESS'd.
  792.  
  793.    SEE ALSO
  794.     CMD_WRITE, S2_BROADCAST, S2_ADDMULTICASTADDRESS
  795.  
  796.    BUGS
  797.  
  798. sana2.device/S2_OFFLINE                               sana2.device/S2_OFFLINE
  799.  
  800.    NAME
  801.     Offline -- Remove interface from service.
  802.  
  803.    FUNCTION
  804.     This command removes a network interface from service.
  805.  
  806.    IO REQUEST
  807.     ios2_Command    - S2_OFFLINE.
  808.  
  809.    RESULTS
  810.     ios2_Error    - Zero if successful; non-zero otherwise.
  811.     ios2_WireError    - More specific error number.
  812.  
  813.    NOTES
  814.     Aborts all pending reads and writes with ios2_Error set to
  815.     S2ERR_OUTOFSERVICE.
  816.  
  817.     While the interface is offline, all read, writes and any other
  818.     command that touches interface hardware will be rejected with
  819.     ios2_Error set to S2ERR_OUTOFSERVICE.
  820.  
  821.     This command is intended to permit a network interface to be
  822.     tested on an otherwise live system.
  823.  
  824.    SEE ALSO
  825.     S2_ONLINE
  826.  
  827.    BUGS
  828.  
  829. sana2.device/S2_ONEVENT                               sana2.device/S2_ONEVENT
  830.  
  831.    NAME
  832.     OnEvent -- Return when specified event occures.
  833.  
  834.    FUNCTION
  835.     This command returns when a particular event condition has occured
  836.     on the network or this network interface.
  837.  
  838.    IO REQUEST
  839.     ios2_Command    - S2_ONEVENT.
  840.     ios2_Flags    - Supported flags are:
  841.                 SANA2IOB_QUICK
  842.     ios2_WireError    - Mask of event(s) to wait for
  843.               (from <devices/sana2.h>).
  844.  
  845.    RESULTS
  846.     ios2_Error    - Zero if successful; non-zero otherwise.
  847.     ios2_WireError    - Mask of events that occured.
  848.  
  849.    NOTES
  850.     If this device driver does not understand the specified event
  851.     condition(s) then the command returns immediately with
  852.     ios2_Req.io_Error set to S2_ERR_NOT_SUPPORTED and ios2_WireError
  853.     S2WERR_BAD_EVENT.  A successful return will have ios2_Error set to
  854.     zero ios2_WireError set to the event number.
  855.  
  856.     All pending requests for a particular event will be returned when
  857.     that event occurs.
  858.  
  859.     All event types that cover a particular condition are returned when
  860.     that condition occures. For instance, if an error is returned by
  861.     a buffer management function during receive processing, events of
  862.     types S2EVENT_ERROR, S2EVENT_RX and S2EVENT_BUFF would be returned if
  863.     pending.
  864.  
  865.     Types ONLINE and OFFLINE return immediately if the device is
  866.     already in the state to be waited for.
  867.  
  868.    SEE ALSO
  869.  
  870.    BUGS
  871.  
  872. sana2.device/S2_ONLINE                                 sana2.device/S2_ONLINE
  873.  
  874.    NAME
  875.     Online -- Put a network interface back in service.
  876.  
  877.    FUNCTION
  878.     This command places an offline network interface back into service.
  879.  
  880.    IO REQUEST
  881.     ios2_Command    - S2_ONLINE.
  882.  
  883.    RESULTS
  884.     ios2_Error    - Zero if successful; non-zero otherwise.
  885.     ios2_WireError    - More specific error number.
  886.  
  887.    NOTES
  888.     This command is responsible for putting the network interface
  889.     hardware back into a known state (as close as possible to the
  890.     state before S2_OFFLINE) and resets the unit global and special
  891.     statistics.
  892.  
  893.    SEE ALSO
  894.     S2_OFFLINE
  895.  
  896.    BUGS
  897.  
  898. sana2.device/S2_READORPHAN                         sana2.device/S2_READORPHAN
  899.  
  900.    NAME
  901.     ReadOrphan -- Get a packet for which there is no reader.
  902.  
  903.    FUNCTION
  904.     Get the next packet available that does not satisfy any    then-pending
  905.     CMD_READ requests. The data returned in the ios2_Data structure is
  906.     normally the Data Link Layer packet type field and the packet data. If
  907.     bit SANA2IOB_RAW is set in ios2_Flags, then the entire Data Link Layer
  908.     packet, including both header and trailer information, will be
  909.     returned.
  910.  
  911.    IO REQUEST
  912.     ios2_Command    - CMD_READORPHAN.
  913.     ios2_Flags    - Supported flags are:
  914.                 SANA2IOB_RAW
  915.                 SANA2IOB_QUICK
  916.     ios2_DataLength    - Length of the Data to be sent.
  917.     ios2_Data    - Abstract data structure which packet data is
  918.               contained in.
  919.  
  920.    RESULTS
  921.     ios2_Error    - Zero if successful; non-zero otherwise.
  922.     ios2_WireError    - More specific error number.
  923.     ios2_Flags    - The following flags may be returned:
  924.                 SANA2IOB_RAW
  925.                 SANA2IOB_BCAST
  926.                 SANA2IOB_MCAST
  927.     ios2_SrcAddr    - Source interface address of packet.
  928.     ios2_DstAddr    - Destination interface address of packet.
  929.     ios2_DataLength    - Length of the Data to be sent.
  930.     ios2_Data    - Abstract data structure which packet data is
  931.               contained in.
  932.  
  933.    NOTES
  934.     This is intended for debugging and management tools.  Protocols should
  935.     not use this.
  936.  
  937.     To determine which protocol family the returned packet belongs to you
  938.     may have to specify SANA2IOB_RAW to get the entire data link layer
  939.     wrapper (which is where the protocol type may be kept). Notice this
  940.     necessarily means that this cannot be done in a network interface
  941.     independent fashion.
  942.  
  943.    SEE ALSO
  944.     CMD_READ, CMD_WRITE
  945.  
  946.    BUGS
  947.  
  948. sana2.device/S2_TRACKTYPE                           sana2.device/S2_TRACKTYPE
  949.  
  950.    NAME
  951.     TrackType -- Accumulate statistics about a packet type.
  952.  
  953.    FUNCTION
  954.     This command causes the device driver to accumulate statistics about
  955.     a particular packet type. Packet type statistics, for the particular
  956.     packet type, are zeroed by this command.
  957.  
  958.    IO REQUEST
  959.     ios2_Command    - S2_TRACKTYPE.
  960.     ios2_PacketType    - Pointer to the packet type of interest.
  961.  
  962.    RESULTS
  963.     ios2_Error    - Zero if successful; non-zero otherwise.
  964.     ios2_WireError    - More specific error number.
  965.  
  966.    NOTES
  967.  
  968.    SEE ALSO
  969.     S2_UNTRACKTYPE, S2_GETTYPESTATS
  970.  
  971.    BUGS
  972.  
  973. sana2.device/S2_UNTRACKTYPE                       sana2.device/S2_UNTRACKTYPE
  974.  
  975.    NAME
  976.     UntrackType -- End statistics about a packet type.
  977.  
  978.    FUNCTION
  979.     This command causes the device driver to stop accumulating
  980.     statistics about a particular packet type.
  981.  
  982.    IO REQUEST
  983.     ios2_Command    - S2_UNTRACKTYPE.
  984.     ios2_PacketType    - Pointer to the packet type of interest.
  985.  
  986.    RESULTS
  987.     ios2_Error    - Zero if successful; non-zero otherwise.
  988.     ios2_WireError    - More specific error number.
  989.  
  990.    NOTES
  991.  
  992.    SEE ALSO
  993.     S2_TRACKTYPE, S2_GETTYPESTATS
  994.  
  995.    BUGS
  996.  
  997.  
  998.